adTempus API
Prior to adTempus 4, the API was implemented in a COM (ActiveX) component, exposed to .NET clients through .NET/COM Interop. For version 4 the client has been rewritten as a native .NET assembly. In doing so we have shifted away from many limitations imposed by the COM paradigm and have greatly improved the API in terms of usability. Due to the scope of the changes it was not feasible to maintain strict backward compatibility with previous versions of the API. However, the basic structure of the API remains the same, and most breaking changes are easy to identify and correct.
Major breaking changes are discussed below.
For adTempus 4 the client/server communication layer has been rewritten. Connections between adTempus 4 (and later) clients and adTempus 3 (and earlier) servers, and vice versa, are not supported. An application that needs to connect to two versions of the adTempus server will need to use two versions of the client API.
As in prior versions, the Scheduler object represents a session with the adTempus server and is the starting point for all interactions with an adTempus server. Most methods for fetching and manipulating objects have been moved to the DataContext (see next section).
In previous versions, each Scheduler session used a single object cache, so multi-threaded applications needed multiple Scheduler sessions to provide isolation when modifying objects. Beginning with version 4 the Scheduler still represents the session, but most object retrieval/manipulation is performed through a DataContext that belongs to the Scheduler. Each DataContext and the objects associated with it are isolated from other DataContexts: if you fetch the same Job from two different DataContexts, you will have two independent copies of the Job, and changes that you make to one copy will not be reflected in the other.
Your application should create a new DataContext (using Scheduler.NewDataContext) for each functional operation. For example, in the adTempus Console, when you edit a top-level object such as a Job, the Console creates a new DataContext and fetches the job in that context before displaying the editor. All edits to the job take place within that DataContext, keeping them isolated from the rest of the Console until the job is saved.
Important: Objects fetched or created in one DataContext cannot be used in another. For example, you cannot fetch a Job in one DataContext and then try to assign it a CredentialProfile that was fetched in a different DataContext. If you attempt this, the set operation will throw a BoundaryViolationException.
Previous versions of the API recommended that each Scheduler object be used by only a single thread, and that you create multiple Scheduler sessions to support multithreaded operations. Beginning with version 4 you can use a single Scheduler object for each server connection, with multiple DataContexts to support multiple threads and other isolation needs.
Prior to version 4, objects were fetched using one of the Scheduler object's generic GetObject... methods, which required cumbersome query objects in order to filter the objects being fetched. Beginning with version 4, object fetch is handled by the DataContext, which has Get methods tailored to each type of object. For example, the GetJob method supports fetching a job by name, and various GetJobs methods provide other filtering options. Similarly, there are GetJobGroup and GetJobGroups, GetCredentialProfile and GetCredentialProfiles, etc.
Each ADTObject object is uniquely identified by an OID. In prior versions this was a string value consisting of two GUIDs joined by a colon. Beginning with version 4, the OID property returns an object of class OID, which encapsulates class identification and object identification. The OID.ToLongString method returns the string representation used in prior versions. The OID constructor, ParseOID, and Create methods all accept strings in the old OID format.
Most enums are now defined in the ArcanaDevelopment.adTempus.Shared namespace rather than ArcanaDevelopment.adTempus.Client.
The names of some enums have been changed to clean up and standardize naming. Most notably:
Other changes will be easy to identify and correct based on compilation errors.
Other notable changes are described below.
When you save a single top-level object (such as a Job), any dirty objects that it owns or references are also saved in a single database transaction. However, previous versions of the API offered no means for transactional updates to multiple top-level objects (such as saving several jobs at once). The UnitOfWork has been added to support transactional update/delete operations. Use DataContext.CreateUnitOfWork to create a UnitOfWork, then use AddForSave and AddForDelete to add objects to save/delete. Finally, call Commit to commit the changes in a single transaction.